﻿<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools Documentation - Element/Element.Event</title>
</head>

<body>
  <div id="docs" class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Element">Element</a></h4>
			<div class="menu-item"><a href="#Element:addEvent">addEvent</a></div>
			<div class="menu-item"><a href="#Element:removeEvent">removeEvent</a></div>
			<div class="menu-item"><a href="#Element:addEvents">addEvents</a></div>
			<div class="menu-item"><a href="#Element:removeEvents">removeEvents</a></div>
			<div class="menu-item"><a href="#Element:fireEvent">fireEvent</a></div>
			<div class="menu-item"><a href="#Element:cloneEvents">cloneEvents</a></div>
			<h4 class="menu-item"><a href="#Element-Events">Element.Events</a></h4>
			<div class="menu-item"><a href="#"></a></div>
    </div>
    <div class="l-border r-border span-15 content">
				<h1 id="Element"><a href="#Element">Type: Element</a></h1>

<ul class="description">
<li>Custom Type to allow all of its methods to be used with any DOM element via the dollar function <a href="Element.html#Window:dollar">$</a>.</li>
<li>These methods are also available on window and document.</li>
</ul>
<h3>Notes:</h3>

<ul>
<li>Internet Explorer fires element events in random order if they are not fired by <a href="#Element:fireEvent">Element:fireEvent</a>.</li>
</ul>
<h2 id="Element:addEvent"><a href="#Element:addEvent">Element Method: addEvent</a></h2>

<p class="description">Attaches an event listener to a DOM element.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElement.<span class="me1">addEvent</span><span class="br0">(</span>type, fn<span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>type - (<em>string</em>) The event name to monitor ('click', 'load', etc) without the prefix 'on'.</li>
<li>fn   - (<em>function</em>) The function to execute.</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<h5>HTML:</h5>

<pre class="javascript">&lt;div id=<span class="st0">"myElement"</span>&gt;Click me.&lt;/div&gt;
</pre>

<h5>JavaScript</h5>

<pre class="javascript">$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click'</span>, <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>
    <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'clicked!'</span><span class="br0">)</span>;
<span class="br0">}</span><span class="br0">)</span>;
</pre>

<h3>Notes:</h3>

<ul>
<li>You can stop the Event by returning false in the listener or calling <a href="../Types/domevent.html#DOMEvent:stop">Event:stop</a>.</li>
<li>This method is also attached to Document and Window.</li>
</ul>
<h3>See Also:</h3>

<ul>
<li><a href="http://www.w3schools.com/html/html_eventattributes.asp">w3schools Event Attributes</a></li>
</ul>
<h2 id="Element:removeEvent"><a href="#Element:removeEvent">Element Method: removeEvent</a></h2>

<p class="description">Works as Element.addEvent, but instead removes the specified event listener.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElement.<span class="me1">removeEvent</span><span class="br0">(</span>type, fn<span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>type - (<em>string</em>) The event name.</li>
<li>fn   - (<em>function</em>) The function to remove.</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<h4>Standard usage:</h4>

<pre class="javascript"><span class="kw2">var</span> destroy = <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span> <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'Boom: '</span> + <span class="kw1">this</span>.<span class="me1">id</span><span class="br0">)</span>; <span class="br0">}</span> <span class="co1">// this refers to the Element.</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click'</span>, destroy<span class="br0">)</span>;
&nbsp;
<span class="co1">//later...</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">removeEvent</span><span class="br0">(</span><span class="st0">'click'</span>, destroy<span class="br0">)</span>;
</pre>

<h4>Examples with bind:</h4>

<pre class="javascript"><span class="kw2">var</span> destroy = <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span> <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'Boom: '</span> + <span class="kw1">this</span>.<span class="me1">id</span><span class="br0">)</span>; <span class="br0">}</span>
<span class="kw2">var</span> boundDestroy = destroy.<span class="me1">bind</span><span class="br0">(</span>$<span class="br0">(</span><span class="st0">'anotherElement'</span><span class="br0">)</span><span class="br0">)</span>;
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click'</span>, boundDestroy<span class="br0">)</span>;
&nbsp;
<span class="co1">//later...</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">removeEvent</span><span class="br0">(</span><span class="st0">'click'</span>, destroy<span class="br0">)</span>; <span class="co1">// this won't remove the event.</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">removeEvent</span><span class="br0">(</span><span class="st0">'click'</span>, destroy.<span class="me1">bind</span><span class="br0">(</span>$<span class="br0">(</span><span class="st0">'anotherElement'</span><span class="br0">)</span><span class="br0">)</span>; <span class="co1">// this won't remove the event either.</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">removeEvent</span><span class="br0">(</span><span class="st0">'click'</span>, boundDestroy<span class="br0">)</span>; <span class="co1">// the correct way to remove the event.</span>
</pre>

<h3>Notes:</h3>

<ul>
<li>When the function is added using <a href="../Types/Function.html#bind">Function:bind</a> or <a href="../Types/Function.html#pass">Function:pass</a>, etc, a new reference is created.  For removeEvent to work, you must pass a reference to the exact function to be removed.</li>
<li>This method is also attached to Document and Window.</li>
</ul>
<h2 id="Element:addEvents"><a href="#Element:addEvents">Element Method: addEvents</a></h2>

<p class="description">The same as <a href="#Element:addEvent">Element:addEvent</a>, but accepts an object to add multiple events at once.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElement.<span class="me1">addEvents</span><span class="br0">(</span>events<span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>events - (<em>object</em>) An object with key/value representing: key the event name, and value the function that is called when the Event occurs.</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<pre class="javascript">$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvents</span><span class="br0">(</span><span class="br0">{</span>
    mouseover: <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>
        <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'mouseover'</span><span class="br0">)</span>;
    <span class="br0">}</span>,
    click: <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>
        <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'click'</span><span class="br0">)</span>;
    <span class="br0">}</span>
<span class="br0">}</span><span class="br0">)</span>;
</pre>

<h3>Notes:</h3>

<ul>
<li>This method is also attached to Document and Window.</li>
</ul>
<h3>See Also:</h3>

<ul>
<li><a href="#Element:addEvent">Element:addEvent</a></li>
</ul>
<h2 id="Element:removeEvents"><a href="#Element:removeEvents">Element Method: removeEvents</a></h2>

<p class="description">Removes all events of a certain type from an Element. If no argument is passed, removes all events of all types.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElements.<span class="me1">removeEvents</span><span class="br0">(</span><span class="br0">[</span>events<span class="br0">]</span><span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>events - (optional) if not passed removes all events from the element.

<ul>
<li>(<em>string</em>) The event name (e.g. 'click'). Removes all events of that type.</li>
<li>(<em>object</em>) An object of type function pairs. Like the one passed to <a href="#Element:addEvent">Element:addEvent</a>.</li>
</ul>
</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<pre class="javascript"><span class="kw2">var</span> myElement = $<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>;
myElement.<span class="me1">addEvents</span><span class="br0">(</span><span class="br0">{</span>
    mouseover: <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>
        <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'mouseover'</span><span class="br0">)</span>;
    <span class="br0">}</span>,
    click: <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>
        <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'click'</span><span class="br0">)</span>;
    <span class="br0">}</span>
<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
myElement.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click'</span>, <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span> <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'clicked again'</span><span class="br0">)</span>; <span class="br0">}</span><span class="br0">)</span>;
myElement.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click'</span>, <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span> <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'clicked and again :('</span><span class="br0">)</span>; <span class="br0">}</span><span class="br0">)</span>;
<span class="co1">//addEvent will keep appending each function.</span>
<span class="co1">//Unfortunately for the visitor, there will be three alerts they'll have to click on.</span>
myElement.<span class="me1">removeEvents</span><span class="br0">(</span><span class="st0">'click'</span><span class="br0">)</span>; <span class="co1">// saves the visitor's finger by removing every click event.</span>
</pre>

<h3>Notes:</h3>

<ul>
<li>This method is also attached to Document and Window.</li>
</ul>
<h3>See Also:</h3>

<ul>
<li><a href="#Element:removeEvent">Element:removeEvent</a></li>
</ul>
<h2 id="Element:fireEvent"><a href="#Element:fireEvent">Element Method: fireEvent</a></h2>

<p class="description">Executes all events of the specified type present in the Element.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElement.<span class="me1">fireEvent</span><span class="br0">(</span>type<span class="br0">[</span>, args<span class="br0">[</span>, delay<span class="br0">]</span><span class="br0">]</span><span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>type  - (<em>string</em>) The event name (e.g. 'click')</li>
<li>args  - (<em>mixed</em>, optional) Array or single object, arguments to pass to the function. If more than one argument, must be an array.</li>
<li>delay - (<em>number</em>, optional) Delay (in ms) to wait to execute the event.</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<pre class="javascript"><span class="co1">// fires all the added 'click' events and passes the Element 'anElement' after one second</span>
$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">fireEvent</span><span class="br0">(</span><span class="st0">'click'</span>, $<span class="br0">(</span><span class="st0">'anElement'</span><span class="br0">)</span>, <span class="nu0">1000</span><span class="br0">)</span>;
</pre>

<h3>Notes:</h3>

<ul>
<li>This will not fire the DOM Event (this concerns all inline events ie. onmousedown="..").</li>
<li>This method is also attached to Document and Window.</li>
</ul>
<h2 id="Element:cloneEvents"><a href="#Element:cloneEvents">Element Method: cloneEvents</a></h2>

<p class="description">Clones all events from an Element to this Element.</p>

<h3>Syntax:</h3>

<pre class="javascript">myElement.<span class="me1">cloneEvents</span><span class="br0">(</span>from<span class="br0">[</span>, type<span class="br0">]</span><span class="br0">)</span>;
</pre>

<h3>Arguments:</h3>

<ol>
<li>from - (<em>element</em>) Copy all events from this Element.</li>
<li>type - (<em>string</em>, optional) Copies only events of this type. If null, copies all events.</li>
</ol>
<h3>Returns:</h3>

<ul>
<li>(<em>element</em>) This Element.</li>
</ul>
<h3>Examples:</h3>

<pre class="javascript"><span class="kw2">var</span> myElement = $<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>;
<span class="kw2">var</span> myClone = myElement.<span class="me1">clone</span><span class="br0">(</span><span class="br0">)</span>.<span class="me1">cloneEvents</span><span class="br0">(</span>myElement<span class="br0">)</span>; <span class="co1">// clones the element and its events</span>
</pre>

<h3>Notes:</h3>

<ul>
<li>This method is also attached to Document and Window.</li>
</ul>
<h1 id="Element-Events"><a href="#Element-Events">Object: Element.Events</a></h1>

<p class="description">You can add additional custom events by adding properties (objects) to the Element.Events Object</p>

<h3>Arguments:</h3>

<p>The Element.Events.yourProperty (object) can have:</p>

<ol>
<li>base - (<em>string</em>, optional) the base event the custom event will listen to. Its not optional if condition is set.</li>
<li>condition - (<em>function</em>, optional) the condition from which we determine if the custom event can be fired. Is bound to the element you add the event to. The Event is passed in.</li>
<li>onAdd - (<em>function</em>, optional) the function that will get fired when the custom event is added. Is bound to the element you add the event to.</li>
<li>onRemove - (<em>function</em>, optional) the function that will get fired when the custom event is removed. Is bound to the element you add the event to.</li>
</ol>
<h3>Examples:</h3>

<pre class="javascript">Element.<span class="me1">Events</span>.<span class="me1">shiftclick</span> = <span class="br0">{</span>
    base: <span class="st0">'click'</span>, <span class="co1">// the base event type</span>
    condition: <span class="kw2">function</span><span class="br0">(</span>event<span class="br0">)</span><span class="br0">{</span> <span class="co1">//a function to perform additional checks</span>
        <span class="kw1">return</span> <span class="br0">(</span>event.<span class="me1">shift</span> == <span class="kw2">true</span><span class="br0">)</span>; <span class="co1">// this means the event is free to fire</span>
    <span class="br0">}</span>
<span class="br0">}</span>;
&nbsp;
$<span class="br0">(</span><span class="st0">'myInput'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'shiftclick'</span>, <span class="kw2">function</span><span class="br0">(</span>event<span class="br0">)</span><span class="br0">{</span>
    log<span class="br0">(</span><span class="st0">'the user clicked the left mouse button while holding the shift key'</span><span class="br0">)</span>;
<span class="br0">}</span><span class="br0">)</span>;
</pre>

<h3>Notes:</h3>

<ul>
<li>There are different types of custom Events you can create:

<ol>
<li>Custom Events with only base: they will just be a redirect to the base event.</li>
<li>Custom Events with base and condition: they will be redirect to the base event, but only fired if the condition is met.</li>
<li>Custom Events with onAdd and/or onRemove and any other of the above: they will also perform additional functions when the event is added/removed.</li>
</ol>
</li>
<li>Since MooTools 1.3 this is a native JavaScript Object and not an instance of the deprecated Hash</li>
</ul>
<h3>Warning:</h3>

<p>If you use the condition option you NEED to specify a base type, unless you plan to overwrite a native event.
(highly unrecommended: use only when you know exactly what you're doing).</p>

<h2><a href="#">Built-in Custom Events</a></h2>

<h3 id="Element-Events:mouseenter" class="description">Event: mouseenter</h3>

<p>This event fires when the mouse enters the area of the DOM Element and will not be fired again if the mouse crosses over children of the Element (unlike mouseover).</p>

<h4>Examples:</h4>

<pre class="javascript">$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'mouseenter'</span>, myFunction<span class="br0">)</span>;
</pre>

<h4>See Also:</h4>

<ul>
<li><a href="#Element:addEvent">Element:addEvent</a></li>
</ul>
<h3 id="Element-Events:mouseleave">Event: mouseleave</h3>

<p>This event fires when the mouse leaves the area of the DOM Element and will not be fired if the mouse crosses over children of the Element (unlike mouseout).</p>

<h4>Examples:</h4>

<pre class="javascript">$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'mouseleave'</span>, myFunction<span class="br0">)</span>;
</pre>

<h4>See Also:</h4>

<ul>
<li><a href="#Element:addEvent">Element:addEvent</a></li>
</ul>
<h3 id="Element-Events:mousewheel">Event: mousewheel</h3>

<p>This event fires when the mouse wheel is rotated;</p>

<h4>Examples:</h4>

<pre class="javascript">$<span class="br0">(</span><span class="st0">'myElement'</span><span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'mousewheel'</span>, myFunction<span class="br0">)</span>;
</pre>

<h4>Notes:</h4>

<ul>
<li>This custom event just redirects DOMMouseScroll (Mozilla) to mousewheel (Opera, Internet Explorer), making it work across browsers.</li>
</ul>
<h4>See Also:</h4>

<ul>
<li><a href="#Element:addEvent">Element:addEvent</a></li>
</ul>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
